home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 January: Mac OS SDK / Dev.CD Jan 97 SDK2.toast / Development Kits (Disc 2) / OpenDoc Development Framework / ODF-Interest Archive / March 96 / Re starting out < prev    next >
Encoding:
Internet Message Format  |  1996-12-03  |  7.7 KB  |  [TEXT/ttxt]
  1. Subject:     Re: starting out
  2. Sent:        3/14/96 2:58 PM
  3. Received:    3/14/96 2:11 PM
  4. From:        Mark Lanett, mlanett@meer.net
  5. Reply-To:    ODF-Interest@CILabs.ORG
  6. To:          OpenDoc Development Framework Discussion List, ODF-Interest@CILabs.
  7.  
  8. beale@q.continuum.net (Jim Beale) writes:
  9. >If I create a .idl file, how do I compile it?
  10. >
  11. >Do I absolutely need MPW?
  12.  
  13. The short answer is that you use somc to compile it, and yes you need MPW
  14. or ToolServer.
  15.  
  16. I assume you're creating the idl file for an extension. You don't need to
  17. do this to write a part, since ODF handles it for you. There have been a
  18. number of discussions recently about extensions, including our imperfect
  19. support for them in ODF d11, and the misleading or wrong recipes for using
  20. them. I think we have an archive of this mailing list in case you missed
  21. them.
  22.  
  23. But lets just talk about compiling the idl file right now.
  24.  
  25. Table of Contents
  26. 1) What exactly does it mean to compile an idl file?
  27. 2) What tools do you need
  28. 3) How do you install the tools
  29. 4) How do you compile
  30. 5) Common Problems
  31. 6) The Future
  32.  
  33.  
  34.  
  35. 1) What exactly does it mean to compile an idl file?
  36.  
  37. An idl file describes your API in a language-neutral manner. It allows your
  38. code to be called from any language, using any compiler. Three files are
  39. needed to accomplish this: .xih, .xh and .cpp.
  40.  
  41. The .xih file contains tables and other meta-data which will be compiled
  42. into your part, and read by SOM. These tables describe your stub routines
  43. in the .cpp file (below). The .xih file contains one structure, called
  44. (MODULE)(PART)ClassInfo, which you need to export from your shared library.
  45.  
  46. The .xh file contains inline C++ classes which will enable other C++-based
  47. parts to call your part. This inline code contains methods for each of the
  48. routines in your IDL file and calls SOM for each one of them, which in turn
  49. calls your code. Going through SOM allows it to translate between calling
  50. conventions of different compilers and languages, and also to transparently
  51. make the function call across a network.
  52.  
  53. The .cpp file contains the stub routines which SOM calls. You implement
  54. your code either directly in these stubs, or call other code written in
  55. something more convenient, like C++ (this is what ODF does). The .cpp file
  56. #includes the .xih file, which is how the meta-data gets into your part.
  57.  
  58. 2) These are the things you need:
  59. MPW (which you can get from the CodeWarrior CD) or ToolServer
  60. The OpenDoc DR4 CD.
  61.  
  62.  
  63.  
  64. 3) And this is what you'll need to do:
  65. 3.1) Install MPW
  66. 3.2) Install SOM into MPW
  67. 3.3) Install ODF into MPW
  68. 3.4) Configure MPW
  69. 3.5) Fix one of the ODF build files
  70.  
  71. 3.1) The CW8 installer will install MPW for you, so you should do that
  72. first. CW8 also comes with ToolServer, but its an old version and people
  73. have reported problems with it. Also, they only have a small file
  74. describing how to set it up. It's easier for now to go with MPW.
  75.  
  76. Once you've installed MPW, launch it, and insert the DR4 CD.
  77.  
  78. 3.2) Open this folder:
  79. Development:CFM-68K and SOMobject:SOMobjectsX for Mac OS:MPW Additions:
  80.  
  81. Each of these folders needs to be copied into your MPW folder. Don't
  82. replace anything,
  83. just add the contents. That is:
  84. Add the files in CIncludes (in Interfaces) to MPW's CIncludes folder. There
  85. are 15.
  86. Add the SOMIncludes folder to MPW's Interfaces folder.
  87. Add the one file (somlib) in SharedLibraries (in Libraries) to MPW's
  88. SharedLibraries folder.
  89. Add the somc file (in Scripts) to MPW's Scripts folder.
  90. Add the 4 tools in Tools to MPW's Tools folder. The Finder will ask you if
  91. you want to replace PPCLink; replace it.
  92. Add the UserStartup*somc file to the MPW folder itself.
  93.  
  94. 3.3) Open this folder:
  95. OpenDoc Development Framework : ODFDev : MPW/ToolServer Additions
  96. Copy the UserStartup*ODF file into your MPW folder.
  97.  
  98. 3.4) Launch MPW
  99.  
  100. MPW will ask you where the ODF folder is. Navigate to your ODF folder (in
  101. your ODFDev folder) and press "Directory".
  102.  
  103. MPW will also ask where the OpenDocSDK is. Navigate to your OpenDoc Headers
  104. (in CodeWarrior : MacOS Support : Headers) and click "Directory".
  105.  
  106. 3.5) Fix one of the ODF build files
  107.  
  108. When we shipped ODF d11, nobody was compiling their own .idl files. We had
  109. commented out the rules which built the .cpp stubs file. Type this in MPW:
  110.         Open "{FWToolsDir}"MacMake.rul
  111. Now do a find on "HLX".  You will see 12 lines which have # signs in front
  112. of them. Remove the #s from lines *except* the first one (with the HLX).
  113. Save this file and close it.
  114.  
  115.  
  116.  
  117. 4) Compiling
  118.  
  119. ODF has default rules for compiling idl files. You will need to add the
  120. file to your part's makefile and run FWBuild.
  121.  
  122. 4.1) Add the file to your makefile
  123. When you generated your part with PartMaker, it created the CodeWarrior
  124. project and an MPW makefile, called MacMake.bmk. The makefile lists all the
  125. output of the idl files, like so:
  126.  
  127. __ComponentSourcesFromIDL = ∂
  128.         "{_FWTargetDir}SOMPart.cpp" d
  129.         "{_FWTargetDir}SOMPart.xh"  d
  130.         "{_FWTargetDir}SOMPart.xih"
  131.  
  132. __ComponentObjects = ∂
  133.         "{_FWObjDir}"SOMPart.cpp.o d
  134.         ...
  135.  
  136. You don't like the .idl file in the makefile, you list the output files.
  137. The Make tool will determine how to build those output files based on our
  138. default rules.
  139.  
  140. If your idl file was called MyInterface.idl, you will add the output files
  141. do those definitions like this:
  142.  
  143. __ComponentSourcesFromIDL = ∂
  144.         "{_FWTargetDir}MyInterface.cpp" d
  145.         "{_FWTargetDir}MyInterface.xih" d
  146.         "{_FWTargetDir}MyInterface.xh" d
  147.         "{_FWTargetDir}SOMPart.cpp" d
  148.         "{_FWTargetDir}SOMPart.xh"  d
  149.         "{_FWTargetDir}SOMPart.xih"
  150.  
  151. __ComponentObjects = ∂
  152.         "{_FWObjDir}"SOMPart.cpp.o d
  153.         ...
  154.  
  155. The "d"s at the end of the lines need to be typed as option-d.
  156.  
  157. You also need to add dependency rules, like this:
  158.  
  159. "{_FWTargetDir}MyInterface.xih" ƒ "{_FWTargetDir}MyInterface.idl"
  160.  
  161. "{_FWTargetDir}MyInterface.xh" ƒ "{_FWTargetDir}MyInterface.idl"
  162.  
  163. "{_FWTargetDir}MyInterface.cpp" ƒ "{_FWTargetDir}MyInterface.idl" d
  164.         "{_FWTargetDir}MyInterface.xh" d
  165.         "{_FWTargetDir}MyInterface.xih"
  166.  
  167. 4.2) Run FWBuild
  168.  
  169. You are finally ready to build. In the MPW Worksheet, type this:
  170. (substitute MyPart with your part's folder's name)
  171. FWBuild -Metrowerks "{ODFDev}MyPart:Sources:MyPart.SOM"
  172.  
  173. You must have your part's folder in the same folder as ODF for this to work.
  174.  
  175. FWBuild will run somc to output your .cpp, .xh, and .xih files. At this
  176. point you can implement your extension. If you change your .idl file, you
  177. need to do this step over again (but only this step). When the SOM compiler
  178. writes your .cpp file it will *not* delete anything, so you don't need to
  179. worry about saving code. It rewrites, not replaces, the .cpp file.
  180.  
  181.  
  182.  
  183. 5) Common Problems
  184.  
  185. You may get "include file not found" errors. This would mean that you are
  186. trying to #include other .idl files which are not found in the standard
  187. OpendDoc or ODF set. You will need to add the locations of those other .idl
  188. files to the makefile. For example, if you were building Cyberdog parts you
  189. would probably have put the PublicIncludes folder in your CodeWarrior
  190. folder, and would need to change the include listing like this:
  191.  
  192. __IDLIncludeDirs = d
  193.         -I "HD:CodeWarrior:MacOS Support:Headers:PublicIncludes:" d
  194.         -I "{FWODIDLIncludes}"
  195.  
  196.  
  197.  
  198. 6) The Future
  199.  
  200. Clearly this process is extremely cumbersome. There are projects underway
  201. to convert SOM into a codewarrior plugin. ToolServer will still be required
  202. for moment, but you won't have to muck with the makefile or FWBuild; you'll
  203. be able to add the .idl file to your project window and treat it mostly
  204. like any other source file.
  205.  
  206. Also, the cross-platform resource compiler (ODFRC) will be a fully native
  207. CW plugin tool for our next release. Now that ODF has view resources,
  208. you'll be using it a lot more.
  209.  
  210.  
  211. --
  212. Mark Lanett <mlanett@meer.net>
  213. Have a bajillion brilliant Jobsian lithium licks
  214.  
  215.